home *** CD-ROM | disk | FTP | other *** search
/ BCI NET / BCI NET Dec 94.iso / archives / programming / utilities / stackcheck.lha / StackCheck / StackCheck.doc < prev    next >
Encoding:
Text File  |  1993-05-05  |  10.0 KB  |  251 lines
  1.                        StackCheck 1.0
  2.                   written by Günther Röhrich
  3.                   this program is Public Domain
  4.  
  5.  
  6. INTRODUCTION
  7.  
  8. StackCheck determines the maximum stack usage of a program. The method it uses
  9. differs completely from all the other stack-watching programs like WatchStack or
  10. Xoper.
  11. This program is intended for developers who want to know the stack usage of
  12. their programs.
  13.  
  14. ADVANTAGES
  15.  
  16. - StackCheck determines the real maximum stack usage and not the maximum
  17.   value of multiple measurements. Therefore even small peaks of stack usage
  18.   will be noticed. (A "small peak" means a stack usage with a duration of only
  19.   a few CPU cycles)
  20.  
  21. - StackCheck doesn't has to be active during the whole runtime of a program.
  22.   It's enough when it is active during the start and the finish of a program.
  23.  
  24. - Stack usage will be noticed even when multitasking is turned off by the
  25.   program which is beeing checked.
  26.  
  27. - For programs started from Workbench it is enough when StackCheck is active
  28.   short time before the program ends. This is enough to determine the maximum
  29.   stack usage correctly.
  30.  
  31. DISADVANTAGES
  32.  
  33. - Stack usage short time that occurs after beginning and before finish of a
  34.   program cannot be determined.  ("short time" means about 0,04 seconds)
  35.   Exception: For programs started from Workbench stack usage that occured even
  36.   very short time after beginning will be determined correctly.
  37.  
  38. - With Kickstart 1.2/1.3 it is not possible to examine programs launched from
  39.   CLI/Shell. (see later)
  40.  
  41. - With Kickstart 2.0 or higher it is impossible to examine BCPL-programs.
  42.   (It will probably cause a system crash when trying to do that)
  43.  
  44.  
  45. NEEDED COMPUTER AND OPERATING SYSTEM
  46.  
  47. StackCheck works on all AMIGAs with all Kickstart versions and with all
  48. processors.
  49. Tested configurations:
  50.  
  51. A500  Kickstart 2.04;1.3  Processor: 68000
  52. A1200 Kickstart 3.00      Processor: 68EC020
  53. A3000 Kickstart 2.04      Processor: 68030
  54.  
  55.  
  56. USAGE OF STACKCHECK
  57.  
  58. The syntax of StackCheck is:
  59.  
  60.  StackCheck Name|* [DELAY=n][PRI=n][STACK=n][NUM=n]
  61.  
  62. To abort StackCheck press CTRL-C.
  63.  
  64.  
  65. Name
  66.  
  67. The name of the program you want to examine has to be given as the first
  68. argument. This name is case-sensitive. If the name contains blanks it must be
  69. put in quotation-marks.
  70. The sign "*" stands for any name. Other wildcards are not supported.
  71.  
  72. All the other arguments are optional. If they are left out an internal default
  73. value will be used. The letter n stands for a number.
  74. (Example: stack=20000)
  75.  
  76.  
  77. DELAY=n
  78.  
  79. n stands for the time period between two examinations of the stack. The unit
  80. is 1/50 second. The default value is 2.
  81.  
  82.  
  83. PRI=n
  84.  
  85. This will set the priority of the StackCheck task to n. The default value is 1.
  86.  
  87.  
  88. STACK=n
  89.  
  90. StackCheck will only examine a program if its stack size is equal to n. 
  91. (This is useful if "*" is used for the name)
  92.  
  93.  
  94. NUM=n
  95.  
  96. StackCheck will only examine a program if its CLI-number is equal to n. The
  97. CLI-number is usually displayed in the CLI/Shell prompt.
  98. (This is useful if "*" is used for the name)
  99.  
  100.  
  101. STACKCHECK'S WORKING METHOD
  102.  
  103. Note: If you're not familiar on how the processor stack works please read the
  104. chapter "How The Stack Works".
  105.  
  106. First of all, the unused area of the stack is filled with the pattern $BEEF.
  107. If a program is using more stack the pattern will be overwritten. To determine
  108. the maximum stack usage it's sufficient to count how large the undamaged area
  109. still is. This measurement must be repeated because it's impossible to know
  110. when the program will end. The only measurement that counts is the last one.
  111.  
  112. At the start of StackCheck it checks if the program already runs. If not it
  113. waits a period and it checks again if the program has been started in the mean
  114. time. (This period can be set with the DELAY-option)
  115.  
  116. If the program is found the first two words at the lower end of the stack will
  117. be examined. If the fill pattern $BEEF is found nothing will be done. If they
  118. contained zeros then the program must have been started from Workbench. At the
  119. very beginning the complete stack area contained zeros. Therefore, all the zeros
  120. beginning from the lower end of the stack will be replaced by the fill pattern
  121. $BEEF. If a word is found that does not contain zero this will be stopped. This
  122. is also the place of the maximum stack usage that occured so far. The filling
  123. procedure will also be stopped when the actual stack pointer is reached. This
  124. must be done to leave the program undamaged.
  125. If the first two words at the lower end of the stack contained an unknown
  126. pattern then the free stack area up to the actual stack pointer will be filled
  127. with the pattern $BEEF. This is the case if the program has been started from
  128. CLI/Shell. Then it is impossible to determine the maximum stack usage that
  129. occured before the filling process.
  130.  
  131. After this preliminary work StackCheck will determine how far the pattern
  132. $BEEF remaines undamaged. This marks the place of the maximum stack usage
  133. that occured so far. This procedure will stop if CTRL-C is pressed or the
  134. program ends. (The delay between two examinations can be set with the
  135. DELAY-option.)
  136.  
  137. When StackCheck is stopped the results of the last measurement will be
  138. printed. The results of the other measurements are not needed. Therefore it is
  139. not necessary to let StackCheck do its measurements during the whole runtime
  140. of the program.
  141. If you know when the program ends it is recommended to stop StackCheck by
  142. pressing  CTRL-C right after the program has been started. Short time before
  143. the program ends you must launch StackCheck again. When the program ends you
  144. will get the same results as when StackCheck was active all the time.
  145. With programs started from Workbench it is enough when StackCheck was active
  146. before the program finishes. However, it is recommended to activate StackCheck
  147. at the beginning of the program so that the zeros will be replaced by the more
  148. reliable pattern $BEEF.
  149.  
  150.  
  151. ANALYSING THE OUTPUT OF STACKCHECK
  152.  
  153. A typical output of StackCheck looks like this:
  154.  
  155. StackCheck V1.0 by Günther Röhrich
  156. This program is Public Domain. Press CTRL-C to abort.
  157.  
  158. Free stack area contained unknown pattern:
  159. 00290F58: 000A3EDF 00000FA0 00292454 00000001
  160. Stack OK:
  161. 00290F58: BEEFBEEF BEEFBEEF BEEFBEEF BEEFBEEF
  162. Stacksize: 4000
  163. Used max:  2818
  164.  
  165. First of all the first 16 bytes beginning from the lower end of the stack
  166. will be printed. This is the status as found by StackCheck. The number before
  167. the colon is the address of the lower end of the stack. Then the same area
  168. is printed again as it looked at the last examination of the stack. If a stack
  169. overflow occured a warning message will be printed. It is impossible to detect
  170. how much the stack overflowed. Then the stacksize and the maximum stack usage
  171. will be printed.
  172. If StackCheck detects that another stack area outside of the normal area has
  173. been used it will display a corresponding message. It is possible for example by
  174. using exec's StackSwap() function. This cannot always be detected.
  175.  
  176.  
  177. PROBLEMS
  178.  
  179. At the beginning I mentioned that the stack usage short time after the start
  180. and short time before the end of a program cannot be determined. If somebody
  181. writes a program it is recommended to insert a short delay as the first and
  182. last command in the program. (for example with the command Delay(50))
  183. Of course, it is better wenn the start and finish of the program has an inter-
  184. action with the user.
  185.  
  186. As mentioned before it is not possible to examine programs started from
  187. CLI/Shell under Kickstart 1.2/1.3. To avoid system crashes it is recommended
  188. to use only programs started from Workbench.
  189.  
  190. Under Kickstart 2.0 or higher it is impossible to examine BCPL programs because
  191. this will crash your system. In this case some memory is used in the free stack
  192. area. This area will be overwritten with the pattern $BEEF. BCPL programs are
  193. normally not used with Kickstart 2.0 or higher, therefore I haven't done
  194. anything against this.
  195.  
  196. If programs are using the free stack area for any purpose (for example to detect
  197. a stack overflow by themselves) some problems may occur. Please contact me if
  198. you have such a program. (I dont't have one)
  199.  
  200. When a program is launched several times it is possible that StackCheck reports
  201. slightly different values for the maximum stack usage, even when the program
  202. performs the same activities every time. This is not StackCheck's fault. It
  203. depends on the moment when the program is interrupted by task-switching or
  204. interrupts. (In this case about 70 bytes will be stored on the stack.)
  205.  
  206.  
  207. HOW THE STACK WORKS
  208.  
  209. This chapter is intended for those who are not familiar on how the stack works.
  210. For all the other there is no need to read it.
  211.  
  212. The processor stack of the MC680x0 grows from higher addresses towards lower
  213. addresses. The register A7 is used as a stack pointer. It points at the last
  214. address of the last item on the stack. To avoid address errors A7 is kept word
  215. aligned. For compatibility reasons this is the same on the 68020 or higher
  216. although these processors don't have address errors.
  217. The stack itself may have any size, the system does not check if the stack goes
  218. beyond the limits. (With a MMU it could be possible)
  219. The stack is used to store temporary variables and return addresses at function
  220. calls. When an interrupt occurs the state of the processor is also stored on the
  221. stack to allow the program to be continued.
  222. The AMIGA stores the stack pointer at an interruption of a program in the
  223. variable SPReg of the task structure. The variables SPUpper and SPLower contain
  224. the upper and lower end of the stack. (This is not always the case when
  225. Kickstart 1.2/1.3 is used.)
  226.  
  227.  
  228. ADDRESS OF THE AUTHOR AND OTHER NOTES
  229.  
  230. StackCheck is Public Domain, therefore you can do what you want with it. To
  231. avoid confusions among the users please contact me if you want to distribute
  232. a modified version. 
  233. If you find a bug please let me know about it. I am also happy if somebody sends
  234. me a corrected version of the English documentation. (As you can see my English
  235. is not very good)
  236.  
  237. Address:
  238.  
  239.           Günther Röhrich
  240.           Lerchenbergstr. 4
  241.           W-7300 Esslingen
  242.             Germany
  243.  
  244.  
  245. New address beginning from 1. July 1993:
  246.  
  247.           Günther Röhrich
  248.           Lerchenbergstr. 4
  249.           73733 Esslingen
  250.             Germany
  251.